<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<html>
<head>
<!-- Copyright 1997 The Open Group, All Rights Reserved -->
<title>sigstack</title>
</head><body bgcolor=white>
<center>
<font size=2>
The Single UNIX &reg; Specification, Version 2<br>
Copyright &copy; 1997 The Open Group

</font></center><hr size=2 noshade>
<h4><a name = "tag_000_008_732">&nbsp;</a>NAME</h4><blockquote>
sigstack - set and/or get alternate signal stack context
(<b>LEGACY</b>)
</blockquote><h4><a name = "tag_000_008_733">&nbsp;</a>SYNOPSIS</h4><blockquote>
<pre><code>

#include &lt;<a href="signal.h.html">signal.h</a>&gt;

int sigstack(struct sigstack *<i>ss</i>, struct sigstack *<i>oss</i>);
</code>
</pre>
</blockquote><h4><a name = "tag_000_008_734">&nbsp;</a>DESCRIPTION</h4><blockquote>
The
<i>sigstack()</i>
function allows the calling process to indicate to the system an area of its
address space to be used for processing signals received by the process.
<p>
If the <i>ss</i> argument is not a null pointer, it must
point to a <b>sigstack</b> structure.
The length of the application-supplied stack must be at least SIGSTKSZ bytes.
If the alternate signal stack overflows, the resulting behaviour is
undefined.  (See APPLICATION USAGE below.)
<ul>
<p>
<li>
The value of the
<b>ss_onstack</b>
member indicates whether the process wants the system
to use an alternate signal stack when delivering signals.
<p>
<li>
The value of the
<b>ss_sp</b>
member indicates the desired location
of the alternate signal stack area in the process' address space.
<p>
<li>
If the
<i>ss</i>
argument is a null pointer, the current alternate signal stack context is not
changed.
<p>
</ul>
<p>
If the
<i>oss</i>
argument is not a null pointer, it points to a <b>sigstack</b> structure in
which the current alternate signal stack context is placed.  The value stored
in the
<b>ss_onstack</b>
member of
<i>oss</i>
will be non-zero if the process is currently executing on the alternate signal
stack.  If the
<i>oss</i>
argument is a null pointer, the current alternate signal stack context is not
returned.
<p>
When a signal's action indicates its handler
should execute on the alternate signal stack (specified by calling
<i><a href="sigaction.html">sigaction()</a></i>),
the implementation checks to see if the process is currently executing on that
stack.  If the process is not currently executing on the alternate signal
stack, the system arranges a switch to the alternate signal stack for the
duration of the signal handler's execution.
<p>
After a successful call to one of the
<i>exec</i>
functions, there are no alternate signal stacks in the new process image.
<p>
This interface need not be reentrant.
</blockquote><h4><a name = "tag_000_008_735">&nbsp;</a>RETURN VALUE</h4><blockquote>
Upon successful completion,
<i>sigstack()</i>
returns 0.  Otherwise, it returns -1 and sets <i>errno</i> to indicate the
error.
</blockquote><h4><a name = "tag_000_008_736">&nbsp;</a>ERRORS</h4><blockquote>
The
<i>sigstack()</i>
function will fail if:
<dl compact>

<dt>[EPERM]<dd>
An attempt was made to modify an active stack.

</dl>
</blockquote><h4><a name = "tag_000_008_737">&nbsp;</a>EXAMPLES</h4><blockquote>
None.
</blockquote><h4><a name = "tag_000_008_738">&nbsp;</a>APPLICATION USAGE</h4><blockquote>
A portable application, when being written or rewritten, should use
<i><a href="sigaltstack.html">sigaltstack()</a></i>
instead of
<i>sigstack()</i>.
<p>
On some implementations, stack space is automatically extended as needed.  On
those implementations, automatic extension is typically not available for an
alternate stack.  If a signal stack overflows, the resulting behaviour of the
process is undefined.
<p>
The direction of stack growth is not indicated in the
historical definition of <b>struct sigstack</b>.
The only way to portably establish a stack pointer is for the application
to determine stack growth direction, or to allocate a block of storage
and set the stack pointer to the middle.
The implementation may assume that the size of the signal stack
is SIGSTKSZ as found in
<i><a href="signal.h.html">&lt;signal.h&gt;</a></i>.
An implementation that would like to specify a signal stack size
other than SIGSTKSZ should use
<i><a href="sigaltstack.html">sigaltstack()</a></i>.
<p>
Programs should not use
<i><a href="longjmp.html">longjmp()</a></i>
to leave a signal handler that is running on a stack established with
<i>sigstack()</i>.
Doing so may disable future use of the signal stack.  For abnormal exit from a
signal handler,
<i><a href="siglongjmp.html">siglongjmp()</a></i>,
<i><a href="setcontext.html">setcontext()</a></i>
or
<i><a href="swapcontext.html">swapcontext()</a></i>
may be used.  These functions fully support switching from one stack to
another.
<p>
The
<i>sigstack()</i>
function requires the application to have knowledge of the underlying system's
stack architecture.  For this reason,
<i><a href="sigaltstack.html">sigaltstack()</a></i>
is recommended over this function.
</blockquote><h4><a name = "tag_000_008_739">&nbsp;</a>FUTURE DIRECTIONS</h4><blockquote>
None.
</blockquote><h4><a name = "tag_000_008_740">&nbsp;</a>SEE ALSO</h4><blockquote>
<i><a href="exec.html">exec</a></i>,
<i><a href="fork.html">fork()</a></i>,
<i><a href="_longjmp.html">_longjmp()</a></i>,
<i><a href="longjmp.html">longjmp()</a></i>,
<i><a href="setjmp.html">setjmp()</a></i>,
<i><a href="sigaltstack.html">sigaltstack()</a></i>,
<i><a href="siglongjmp.html">siglongjmp()</a></i>,
<i><a href="sigsetjmp.html">sigsetjmp()</a></i>,
<i><a href="signal.h.html">&lt;signal.h&gt;</a></i>.
</blockquote><hr size=2 noshade>
<center><font size=2>
UNIX &reg; is a registered Trademark of The Open Group.<br>
Copyright &copy; 1997 The Open Group
<br> [ <a href="../index.html">Main Index</a> | <a href="../xshix.html">XSH</a> | <a href="../xcuix.html">XCU</a> | <a href="../xbdix.html">XBD</a> | <a href="../cursesix.html">XCURSES</a> | <a href="../xnsix.html">XNS</a> ]

</font></center><hr size=2 noshade>
</body></html>
